home *** CD-ROM | disk | FTP | other *** search
/ MacWorld 1999 March - Disc 1 / Macworld (1999-03) (Disk 1).dmg / Shareware World / Utilities / Text Processing / Alpha / Help / Documentprojects Help < prev    next >
Encoding:
Text File  |  1997-09-11  |  6.6 KB  |  180 lines  |  [TEXT/ALFA]
  1. ## 
  2.  # ###################################################################
  3.  #  Vince's Additions - an extension package for Alpha
  4.  # 
  5.  #  FILE: "Documentprojects Help"
  6.  #                                    created: 1/8/97 {2:22:17 pm} 
  7.  #                                last update: 11/9/97 {7:39:16 pm} 
  8.  #  Author: Vince Darley
  9.  #  E-mail: <darley@fas.harvard.edu>
  10.  #    mail: Division of Engineering and Applied Sciences, Harvard University
  11.  #          Oxford Street, Cambridge MA 02138, USA
  12.  #     www: <http://www.fas.harvard.edu/~darley/>
  13.  #  
  14.  # Copyright (c) 1997  Vince Darley
  15.  # 
  16.  # ###################################################################
  17.  ##
  18.  
  19.             Personalisation
  20.  
  21. In order to use many of these additions, you need to enter various pieces 
  22. of information which describe yourself, the projects you work on, and 
  23. document templates which you use.  Some of these are accessed from the 
  24. Config->Global menu, under 'User Details', others are handled via the 'New 
  25. Document Type' and 'New Project' menu items (hold down option or ctrl to 
  26. edit or delete document types and projects from this menu).
  27.  
  28. The purpose of 'Projects' is to allow you to have separate templates for 
  29. different things on which you work, and to have different Alpha modes bound 
  30. to different projects by default.
  31.  
  32. The purpose of Document templates is simply to save you the labour of 
  33. typing in the same sort of basic information for every file you create, and 
  34. to give your files a standard look.  Document headers can also contain 
  35. modification and creating dates, version numbering,… all of which may be 
  36. updated very easily.
  37.  
  38. You can modify the following preferences using the 
  39. 'Config->Global->Document Project Prefs…' menu item:
  40.  
  41.     • overrideNew --- over-ride new 
  42.     • docTemplatesModeSpecific --- new document templates mode specific 
  43.       (useful if you have lots of templates) 
  44.     • newDocNamePrompt --- prompt for name of new document? 
  45.     • autoUpdateHeader --- Do we auto-update the time-stamp in the header of 
  46.       a file?
  47.     • untitledDocsAreEmpty --- untitled documents are empty.
  48.     • updateFromInternetConfig --- Do we update user items from internet config? 
  49.     • minItemsInTitlePopup--- number of items in option-title-bar popup before 
  50.       we add glob'ed directory
  51.  
  52. Also from the 'File Utils' and electric menus one can access a variety of 
  53. new functions and an extra hierarchical sub-menu, so that you can easily 
  54. add personalised code-tidbits.  Here are some of the features:
  55.  
  56.     • shift-F2 to update the version number/info of a file header.
  57.     • function and class templates.
  58.     • automatic generation of a pair of (for example) .h/.cc files for a new 
  59.       class.
  60.     • file-header time-stamp and version details updating
  61.     • comment block generation for procedures
  62.  
  63. The electric menu contains a 'Templates' sub-menu, which contains global 
  64. templates stored in the variable 'univ::MenuTemplates', and mode-specific
  65. templates stored in variables ${mode}Templates.  The format of these 
  66. variables is a list of names, which correspond to procedures when prepended 
  67. with 'file::'.  You can add new items by using the menu item.
  68.  
  69. The file utils menu also contains a 'More Utils' sub-menu to allow easy 
  70. addition of your own procedures.  Place procedures for that menu in a 
  71. mode-preferences file for the mode to which they apply.
  72.  
  73.             Document templates
  74.  
  75. For each of your different projects and modes you'll probably want a 
  76. standard document template, with a given header, perhaps some code/text 
  77. already filled in,…  You can use the Config->Global menu to create, edit 
  78. and remove document templates.  They can be arbitrarily complex.
  79.  
  80.             File headers
  81.  
  82. The file "docProjEngine.tcl" will create new header and source files 
  83. for C, C++ and Tcl code automatically.  As well as creating descriptive 
  84. headers, it can insert actual template code (for a class definition, say).  
  85.  
  86. The easiest way to see what these functions do is to switch to C++ mode, 
  87. and select 'New Class' from the 'File Utils' menu.  Enter any name when 
  88. prompted in the status bar, and you'll see what these procedures produce.  
  89.  
  90.             Function Comments
  91.  
  92. •    F1 ---  plain - insert comment block
  93.             opt   - insert small comment block
  94.             cmd   - insert large comment block
  95.             shift - update function comment block version number
  96.  
  97. Imagine you have the following function (in Tcl for this example):
  98.  
  99.     proc main {} {
  100.         # just for show
  101.         puts stdout "Hello World"
  102.         exit
  103.     }
  104.  
  105. and you wish to write a comment block above it, explaining what it does, 
  106. what it returns, what side-effects it may have, and to note down that you 
  107. are the author.  Just double click on the procedure name 'main' to select 
  108. it, and press F1 (with a modifier if desired) and you have a great 
  109. template, in one of three styles (this is for 'cmd-F1'):
  110.  
  111.     ## 
  112.      # -------------------------------------------------------------------------
  113.      #   
  114.      # "main" --
  115.      #  
  116.      #  
  117.      #          
  118.      # Results:
  119.      #  •
  120.      #  
  121.      # Side effects:
  122.      #  •
  123.      #  
  124.      # --Version--Author------------------Changes-------------------------------  
  125.      #    1.0     <darley@fas.harvard.edu> original
  126.      # -------------------------------------------------------------------------
  127.      ##
  128.     proc main {} {
  129.         # just for show
  130.         puts stdout "Hello World"
  131.         exit
  132.     }
  133.  
  134. Instructions are in the status window below --- you hit Tab to 
  135. move from one bullet mark to the next, hitting return automatically
  136. fills in the left edge of the comment block and indents appropriately!
  137. You'll end up with something like this:
  138.  
  139.     ## 
  140.      # -------------------------------------------------------------------------
  141.      #     
  142.      #    "main" --
  143.      #    
  144.      #     The main procedure
  145.      #     of    my program
  146.      #           
  147.      #    Results:
  148.      #     none
  149.      #    
  150.      #    Side effects:
  151.      #     In    this case just trivial side-effects
  152.      #     
  153.      # --Version--Author------------------Changes-------------------------------  
  154.      #      1.0      <darley@fas.harvard.edu> original
  155.      # -------------------------------------------------------------------------
  156.      ##
  157.     proc main {} {
  158.         # just for show
  159.         puts stdout "Hello World"
  160.         exit
  161.     }
  162.  
  163. Of course the same thing works for C, C++ code etc (and probably other 
  164. modes too; I just haven't tried).  Now if you modify the function, and wish 
  165. to update the version numbering, just put the cursor in the vicinity and 
  166. type shift-F1: the comment is found, an extra version and author detail is 
  167. inserted and you're ready to type your changes!
  168.  
  169. If the above block is too big, try other modifiers for smaller ones.
  170.  
  171. ================================================================================
  172.  
  173.             Auto Update
  174.  
  175. If you want file headers to update the last modified date automatically on 
  176. saving, then make sure you've selected 'auto update header' in the 
  177. universal preferences dialog.
  178.  
  179. ================================================================================
  180.